"""
日志配置模块
~~~~~~~~~~~

该模块提供了DHT爬虫系统的日志配置功能。

基本用法:
    >>> from src.log.logger import setup_logger
    >>> logger = setup_logger('my_crawler')
    >>> logger.info('爬虫启动')

特性:
    - 支持控制台输出
    - 可配置日志级别
    - 标准格式化输出
    - 类型注解支持
"""

import logging
import sys
from typing import Any, Optional
from src.config.settings import APP_NAME, LOG_LEVEL, LOG_FORMAT, LOG_DATE_FORMAT

def setup_logger(name: str) -> logging.Logger:
    """
    配置并返回一个日志记录器实例。
    
    该函数创建一个新的日志记录器，配置日志级别和输出格式。默认输出到控制台，
    使用标准的日志格式：时间 - 名称 - 级别 - 消息。
    
    Args:
        name: str, 可选
            日志记录器的名称，默认为'dht_crawler'。用于在日志消息中标识来源。
        
    Returns:
        logging.Logger:
            配置完成的日志记录器实例。
            
    示例:
        >>> logger = setup_logger('crawler_module')
        >>> logger.info('模块初始化完成')
        2024-01-01 12:00:00 - crawler_module - INFO - 模块初始化完成
        
    注意:
        - 日志级别默认设置为 INFO
        - 日志格式：%(asctime)s - %(name)s - %(levelname)s - %(message)s
        - 输出到标准输出(stdout)
    """
    # 创建日志记录器
    logger = logging.getLogger(APP_NAME + '.' + name)
    logger.setLevel(LOG_LEVEL)

    # 创建并配置控制台处理器
    console_handler = logging.StreamHandler(sys.stdout)
    console_handler.setFormatter(
        logging.Formatter(LOG_FORMAT, LOG_DATE_FORMAT)
    )
    
    # 添加处理器到日志记录器
    logger.addHandler(console_handler)
    return logger 